The Standard C Library

The header <assert.h> defines the assert macro and refers to another macro, NDEBUG which is not defined by <assert.h>.If NDEBUG is defined as a macro name at the point in the source file where <assert.h> is included, the assert macro is defined simply as

#define assert(ignore) ((void) 0)

etruct lconv

char *setlocale(int category, conet char *locale);

setlocale(LC_AU, " C " ) ;

struct lconv *localeconv(void);

Here are all the places where library behavior changes with locale:

• The functions strcoll and strxrrm, declared in <string. w, can change how they collate when category LC-COLLATE changes. The functions declared in <ctype.h>, the print and scan functions, declared in <stdio . h>, and the numeric conversion functions, declared in <stdlib. w, can change how they test and alter certain characters when category LC-CTYPE changes.
• The multibyte functions, declared in <stdlib. w, and the print and scan functions, declared in <stdio. w, can change how they parse and translate multibyte strings when category LC-CTYPE changes.
• The print and scan functions, declared in <stdio.w, and atof and strtod, declared in<stdlib. w, can change what they use for thedecimal point character when category LCJUMERIC changes.
• The strrtime function, declared in <time .w, can change how it converts times to character strings when category LC-TIME changes.
• The localeconv function, declared in <locale .h>, can change what it returns when categories LC-MONETARY or LC-NUMERIC change.

Synopsis
    #include <math.h>
    double ac on(doub1e x);
Description
The acos function computes the principal value of the arc cosine of x. A domain error occurs
for arguments not in the range [-1. +1].

Returns: The acos function returns the arc cosine in the range [0, π] radians

Synopsis #include <math.h> double asin (double x);

Description The asin function computes the principal value of the arc sine of x. A domain error occurs for arguments not in the range [-1, +1].

Returns The asin function returns the arc sine in the range [-π/2, +π/2] radians.

Synopsis #include <math.h> double atan(double x);

Description The atan function computes the principal value of the arc tangent of x.

Returns The atan function returns the arc tangent in the range [-π/2, +π/2] radians.

Synopsis #includ. <math.h> double atan2 (double y, double x) ;

Description The atan2 function computes the principal value of the arc tangent of y/x, using the signs of both arguments to determine the quadrant of the return value. A domain error may occur if both arguments are zero.

Returns The atan2 function returns the arc tangent of y/x, in the range[-/pi, +/pi] radians.

Synopsis #includa <math.h> double con(double x);

Description The cos function computes the cosine of x (measured in radians).

Returns The cos function returns the cosine value.

Synopsis #include <math.h> double sin(double x);

Description The sin function computes the sine of x (measured in radians).

Returns The sin function returns the sine value.

Synopsis #include <math.h> double tan(doub1e x);

Description The tan function returns the tangent of x (measured in radians).

Returns The tan function returns the tangent value.

Synopsis #include <math.h> double comh(doub1e x );

Description The cosh function computes the hyperbolic cosine of x. Arrange error occurs if the magnitude of x is too large.

Returns The cosh function returns the hyperbolic cosine value.

Synopsis #includa <math.h> double ainh(double x);

Description The sinh function computes the hyperbolic sine of x. A range error occurs if the magnitude of x is too large.

Returns The sinh function returns the hyperbolic sine value.

Synopsis #include <math.h> double tanh(doub1e x);

Description The tanh function computes the hyperbolic tangent of x.

Returns The tanh function returns the hyperbolic tangent value.

Synopsis #include <math.h> double exp (double x):

Description The exp function computes the exponential function of x. Arrange error occurs if the magnitude of x is too large.

Returns The exp function retums the exponential value.

Synopsis #include <math.h> double frexp(dbub1e value. int *exp);

Description The frexp function breaks a floating-point number into a normalized fraction and an integral power of 2. It stores the integer in the i n t object pointed to by exp.

Returns The frexp function returns the value x, such that x is a double with magnitude in the interval [1/2, 1) or zero, and value equals x times 2 raised to the power *exp. If value is zero, both parts of the result are zero.

Synopsis #include <math.h> dbuble ldexp(doub1e x, int exp);

Description The ldexp function multiplies a floating-point number by an integral power of 2. A range error may occur.

Returns The ldexp function retunls the value of x times 2 raised to the power exp.

Synopsis #include <math.h> double log(double x);

Description The log function computes the natural logarithm of x. A domain error occurs if the argument is negative. A range error may occur if the argument is zero.

Returns The log function returns the natural logarithm.

Synopsis #include <math.h> double log10 (double x);

Description The log10 function computes the base-ten logarithm of x. A domain error occurs if the argument is negative. A range error may occur if the argument is zero.

Return The log10 function returns the base-ten logarithm.

Synopsis #include <math.h> =double modf(doub1e value, double aiptr);

Description The modf function breaks the argument value into integer and fraction parts, each of which has the same sign as the argument. It stores the integer part as a double in the object pointed to by iptr.

Returns The modf function returns the signed fractional part of value.

Synopsis #include <math.h> double pow(doub1e x, double y):

Description The p o w function computes x raised to the power y. A domain error occurs if x is negative and y is not an integral value. A domain error occurs if the result cannot be represented when x is zero and y is less than or equal to zero. A range error may occur.

Returns The p o w function returns the value of x raised to the power y.

Synopsis #include <math.h> double mqrt(double x) ;

Description The sqrt function computes the nonnegative square root of x. A domain error occurs if the argument is negative.

Returns The sqrt function returns the value of the square root.

Synopsis #include <math.h> double ceil(doub1e x):

Description The ceil function computes the smallest integral value not less than x.

Returns The ceil function returns the smallest integral value not less than x, expressed as a double.

Synopsis #include <math.h> double fabm(double x);

Description The fabs function computes the absolute value of a floating-point number X.

Returns The fabs function returns the absolute value of X .

Synopsis #include <math.h> double floor(doub1e x);

Description The floor function computes the largest integral value not greater than x.

Returns The floor function returns the largest integral value not greater than x, expressed as a double.

Synopsis #include <math.h> double fmod(doublr x, double y ) ;

Description The fmod function computes the floating-point remainder of x/y.

Returns The fmod function returns the value x - i * y, for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y. If y is zero, whether a domain error occurs or the fmod function returns zero is implementation-defined.

Synopsis #include <stdio.h> void perror(const char *s);

Description The perror function maps the error number in the integer expression errno to an error message. It writes a sequence of characters to the standard error stream thus: first (if s is not a null pointer and the character pointed to by s is not the null character), the string pointed to by s followed by a colon (:) and a space; then an appropriate error message string followed by a new-line character. The contents of the error message strings are the same as those returned by the strerror function with argument ermo, which are implementation-defined

Returns The perror function returns no value.

The Standard C library provides six different print functions, declared as follows:

int fprintf (FILE *stream, const char *format, . .. ); int printf (const char *format, . . ) ; int sprintf(char *dest, const char *format, ...) ; int vfprintf (FILE *stream, const char *format, va- list ap); int vprintf (const char *format, va- list ap); int vsprintf (char *dest, const char *format, va-list ap);

The Standard C library provides three different scan functions, declared as follows:

int fscanf (FILE *stream, const char *format, . . ) ; int scanf (const char *format, . .. ) ; int sscanf (char *src, const char *format, . .. ) ;

To provide some structure for this chapter, I organize the functions into groups six groups:

• integer math (abs , div, labs, and ldiv) - performing simple integer arithmetic
• algorithms (bsearch, qsort, rand, and srand) - capturing operations complex and widespread enough to warrant packaging as library functions
• text conversions (atof, atoi, atol, strtod, strtol, and strtoul)
  • determining encoded arithmetic values from text representations
• multibyte conversions (mblen, mbstowcs, mbtowc, wcstombs, and wctomb) - mapping between multibyte and wide-character encodings
• storage allocation (calloc, free, malloc, and realloc) - managing a heap of data objects
• environmental interactions (abort, atexit, exit, getenv, and system)- interfacing between the program and the execution environment

double strtod (const char* str, char** endptr); Convert string to double

Parses the C-string str interpreting its content as a floating point number and returns its value as a double. If endptr is not a null pointer, the function also sets the value of endptr to point to the first character after the number.

unsigned long int strtoul (const char* str, char** endptr, int base);

Convert string to unsigned long integer

Parses the C-string str, interpreting its content as an integral number of the specified base, which is returned as an value of type unsigned long int.

char* getenv (const char* name);

Get environment string

Retrieves a C-string containing the value of the environment variable whose name is specified as argument. If the requested variable is not part of the environment list, the function returns a null pointer.

The pointer returned points to an internal memory block, whose content or validity may be altered by further calls to getenv (but not by other library functions).

The string pointed by the pointer returned by this function shall not be modified by the program. Some systems and library implementations may allow to change environmental variables with specific functions (putenv, setenv…), but such functionality is non-portable.

void* bsearch (const void* key, const void* base,
               size_t num, size_t size,
               int (*compar)(const void*,const void*));

Binary search in array

Searches the given key in the array pointed by base that is formed by num elements, each of size bytes, and returns a void* pointer to the first entry in the table that matches the search key.

To perform the search, the function performs a series of calls to compar with key as first argument and elements of the array pointed by base as second argument.

Because this function may be optimized to use a non-linear search algorithm (presumably a binary search), the elements that compare less than key using compar should precede those that compare equal, and these should precede those that compare greater. This requirement is fulfilled by any array ordered with the same criteria used by compar (as if sorted with qsort).

void qsort (void* base, size_t num, size_t size,
            int (*compar)(const void*,const void*));

Sort elements of array

Sorts the num elements of the array pointed by base, each element size bytes long, using the compar function to determine the order.

The sorting algorithm used by this function compares pairs of elements by calling the specified compar function with pointers to them as argument.

The function does not return any value, but modifies the content of the array pointed by base reordering its elements as defined by compar.

The order of equivalent elements is undefined.

div_t div (int numer, int denom);
typedef struct {
  int quot;
  int rem;
} div_t;

Integral division

Returns the integral quotient and remainder of the division of numer by denom ( numer/denom ) as a structure of type div_t, ldiv_t or lldiv_t, which has two members: quot and rem.

int mblen (const char* pmb, size_t max);

Get length of multibyte character

Returns the size of the multibyte character pointed by pmb, examining at most max bytes.

mblen has its own internal shift state, which is altered as necessary only by calls to this function. A call to the function with a null pointer as pmb resets the state (and returns whether multibyte characters are state-dependent).

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

int mbtowc (wchar_t* pwc, const char* pmb, size_t max);

Convert multibyte sequence to wide character

The multibyte character pointed by pmb is converted to a value of type wchar_t and stored at the location pointed by pwc. The function returns the length in bytes of the multibyte character.

mbtowc has its own internal shift state, which is altered as necessary only by calls to this function. A call to the function with a null pointer as pmb resets the state (and returns whether multibyte characters are state-dependent).

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

int wctomb (char* pmb, wchar_t wc);

Convert wide character to multibyte sequence

The wide character wc is translated to its multibyte equivalent and stored in the array pointed by pmb. The function returns the length in bytes of the equivalent multibyte sequence pointed by pmb after the call.

wctomb has its own internal shift state, which is altered as necessary only by calls to this function. A call to the function with a null pointer as pmb resets the state (and returns whether multibyte sequences are state-dependent).

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

size_t mbstowcs (wchar_t* dest, const char* src, size_t max);

Convert multibyte string to wide-character string

Translates the multibyte sequence pointed by src to the equivalent sequence of wide-characters (which is stored in the array pointed by dest), up until either max wide characters have been translated or until a null character is encountered in the multibyte sequence src (which is also translated and stored, but not counted in the length returned by the function).

If max characters are successfully translated, the resulting string stored in dest is not null-terminated.

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

size_t wcstombs (char* dest, const wchar_t* src, size_t max);

Convert wide-character string to multibyte string

Translates wide characters from the sequence pointed by src to the multibyte equivalent sequence (which is stored at the array pointed by dest), up until either max bytes have been translated or until a wide characters translates into a null character.

If max bytes are successfully translated, the resulting string stored in dest is not null-terminated.

The resulting multibyte sequence begins in the initial shift state (if any).

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

int strcoll ( const char * str1, const char * str2 );

Compare two strings using locale

Compares the C string str1 to the C string str2, both interpreted appropriately according to the LC_COLLATE category of the C locale currently selected.

This function starts comparing the first character of each string. If they are equal to each other continues with the following pair until the characters differ or until a null-character signaling the end of a string is reached.

The behavior of this function depends on the LC_COLLATE category of the selected C locale.

size_t strxfrm ( char * destination, const char * source, size_t num );

Transform string using locale

Transforms the C string pointed by source according to the current locale and copies the first num characters of the transformed string to destination, returning its length.

Alternativelly, the function can be used to only retrieve the length, by specifying a null pointer for destination and zero for num.

destination and source shall not overlap.

The behavior of this function depends on the LC_COLLATE category of the selected C locale.

const void * memchr ( const void * ptr, int value, size_t num ); void * memchr ( void * ptr, int value, size_t num );

Locate character in block of memory

Searches within the first num bytes of the block of memory pointed by ptr for the first occurrence of value (interpreted as an unsigned char), and returns a pointer to it.

Both value and each of the bytes checked on the the ptr array are interpreted as unsigned char for the comparison.

char *strchr(const char *str, int c);

Description

The strchr function locates the first occurrence of c (converted to a char) in the string pointed to by s.The terminating null character is considered to be part of the string.

Returns

The strchr function returns a pointer to the located character. or a null pointer if the character does not occur in the string.

size_t strcspn ( const char * str1, const char * str2 );

Get span until character in string

Scans str1 for the first occurrence of any of the characters that are part of str2, returning the number of characters of str1 read before this first occurrence.

The search includes the terminating null-characters. Therefore, the function will return the length of str1 if none of the characters of str2 are found in str1

const char * strpbrk ( const char * str1, const char * str2 ); char * strpbrk ( char * str1, const char * str2 );

Locate characters in string

Returns a pointer to the first occurrence in str1 of any of the characters that are part of str2, or a null pointer if there are no matches.

The search does not include the terminating null-characters of either strings, but ends there.

const char * strrchr ( const char * str, int character ); char * strrchr ( char * str, int character );

Locate last occurrence of character in string

Returns a pointer to the last occurrence of character in the C string str.

The terminating null-character is considered part of the C string. Therefore, it can also be located to retrieve a pointer to the end of a string.

size_t strspn ( const char * str1, const char * str2 );

Get span of character set in string

Returns the length of the initial portion of str1 which consists only of characters that are part of str2.

The search does not include the terminating null-characters of either strings, but ends there

char * strtok ( char * str, const char * delimiters );

Split string into tokens

A sequence of calls to this function split str into tokens, which are sequences of contiguous characters separated by any of the characters that are part of delimiters.

On a first call, the function expects a C string as argument for str, whose first character is used as the starting location to scan for tokens. In subsequent calls, the function expects a null pointer and uses the position right after the end of last token as the new starting location for scanning.

To determine the beginning and the end of a token, the function first scans from the starting location for the first character not contained in delimiters (which becomes the beginning of the token). And then scans starting from this beginning of the token for the first character contained in delimiters, which becomes the end of the token.

This end of the token is automatically replaced by a null-character by the function, and the beginning of the token is returned by the function.

Once the terminating null character of str has been found in a call to strtok, all subsequent calls to this function with a null pointer as the first argument return a null pointer.

The point where the last token was found is kept internally by the function to be used on the next call (particular library implementations are not required to avoid data races).

char * strerror ( int errnum );

Get pointer to error message string

Interprets the value of errnum, generating a string with a message that describes the error condition as if set to errno by a function of the library.

The returned pointer points to a statically allocated string, which shall not be modified by the program. Further calls to this function may overwrite its content (particular library implementations are not required to avoid data races).

The error strings produced by strerror may be specific to each system and library implementation.

Clock ticks per second

This macro expands to an expression representing the number of clock ticks per second.

Clock ticks are units of time of a constant but system-specific length, as those returned by function clock.

Dividing a count of clock ticks by this expression yields the number of seconds.

types declared are size_t.

clock_t clock (void);

Clock program

Returns the processor time consumed by the program.

The value returned is expressed in clock ticks, which are units of time of a constant but system-specific length (with a relation of CLOCKS_PERSEC clock ticks per second).

The epoch used as reference by clock varies between systems, but it is related to the program execution (generally its launch). To calculate the actual processing time of a program, the value returned by clock shall be compared to a value returned by a previous call to the same function.

double difftime (time_t end, time_t beginning);

Return difference between two times

Calculates the difference in seconds between beginning and end.

time_t mktime (struct tm * timeptr);

Convert tm structure to time_t

Returns the value of type time_t that represents the local time described by the tm structure pointed by timeptr (which may be modified).

This function performs the reverse translation that localtime does.

The values of the members tm_wday and tm_yday of timeptr are ignored, and the values of the other members are interpreted even if out of their valid ranges (see struct tm). For example, tm_mday may contain values above 31, which are interpreted accordingly as the days that follow the last day of the selected month.

A call to this function automatically adjusts the values of the members of timeptr if they are off-range or -in the case of tm_wday and tm_yday- if they have values that do not match the date described by the other members.

time_t time (time_t* timer);

Get current time

Get the current calendar time as a value of type time_t.

The function returns this value, and if the argument is not a null pointer, it also sets this value to the object pointed by timer.

The value returned generally represents the number of seconds since 00:00 hours, Jan 1, 1970 UTC (i.e., the current unix timestamp). Although libraries may use a different representation of time: Portable programs should not use the value returned by this function directly, but always rely on calls to other elements of the standard library to translate them to portable types (such as localtime, gmtime or difftime).

 time_t timer;
time(&timer);  /* get current time; same as: timer = time(NULL)  */

char* asctime (const struct tm * timeptr);

Convert tm structure to string

Interprets the contents of the tm structure pointed by timeptr as a calendar time and converts it to a C-string containing a human-readable version of the corresponding date and time.

The returned string has the following format:

Www Mmm dd hh:mm:ss yyyy

Where Www is the weekday, Mmm the month (in letters), dd the day of the month, hh:mm:ss the time, and yyyy the year.

The string is followed by a new-line character ('\n') and terminated with a null-character.

char* ctime (const time_t * timer);

Convert time_t value to string

Interprets the value pointed by timer as a calendar time and converts it to a C-string containing a human-readable version of the corresponding time and date, in terms of local time.

The returned string has the following format:

Www Mmm dd hh:mm:ss yyyy

Where Www is the weekday, Mmm the month (in letters), dd the day of the month, hh:mm:ss the time, and yyyy the year.

The string is followed by a new-line character ('\n') and terminated with a null-character.

This function is equivalent to:

asctime(localtime(timer))

struct tm * gmtime (const time_t * timer);

Convert time_t to tm as UTC time

Uses the value pointed by timer to fill a tm structure with the values that represent the corresponding time, expressed as a UTC time (i.e., the time at the GMT timezone).

For a local time alternative, see localtime.

struct tm * localtime (const time_t * timer);

Convert time_t to tm as local time

Uses the value pointed by timer to fill a tm structure with the values that represent the corresponding time, expressed for the local timezone.

size_t strftime (char* ptr, size_t maxsize, const char* format,
                 const struct tm* timeptr );

Format time as string

Copies into ptr the content of format, expanding its format specifiers into the corresponding values that represent the time described in timeptr, with a limit of maxsize characters.

ormat
C string containing any combination of regular characters and special format specifiers. These format specifiers are replaced by the function to the corresponding values to represent the time specified in timeptr. They all begin with a percentage (%) sign, and are:
specifier       Replaced by     Example
%a      Abbreviated weekday name *      Thu
%A      Full weekday name *     Thursday
%b      Abbreviated month name *        Aug
%B      Full month name *       August
%c      Date and time representation *  Thu Aug 23 14:55:02 2001
%C      Year divided by 100 and truncated to integer (00-99)    20
%d      Day of the month, zero-padded (01-31)   23
%D      Short MM/DD/YY date, equivalent to %m/%d/%y     08/23/01
%e      Day of the month, space-padded ( 1-31)  23
%F      Short YYYY-MM-DD date, equivalent to %Y-%m-%d   2001-08-23
%g      Week-based year, last two digits (00-99)        01
%g      Week-based year 2001
%h      Abbreviated month name * (same as %b)   Aug
%H      Hour in 24h format (00-23)      14
%I      Hour in 12h format (01-12)      02
%j      Day of the year (001-366)       235
%m      Month as a decimal number (01-12)       08
%M      Minute (00-59)  55
%n      New-line character ('\n')       
%p      AM or PM designation    PM
%r      12-hour clock time *    02:55:02 pm
%R      24-hour HH:MM time, equivalent to %H:%M 14:55
%S      Second (00-61)  02
%t      Horizontal-tab character ('\t') 
%T      ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S 14:55
%u      ISO 8601 weekday as number with Monday as 1 (1-7)       4
%U      Week number with the first Sunday as the first day of week one (00-53)  33
%V      ISO 8601 week number (00-53)    34
%w      Weekday as a decimal number with Sunday as 0 (0-6)      4
%W      Week number with the first Monday as the first day of week one (00-53)  34
%x      Date representation *   08/23/01
%X      Time representation *   14:55:02
%y      Year, last two digits (00-99)   01
%Y      Year    2001
%z      ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100)
If timezone cannot be termined, no characters   +100
%Z      Timezone name or abbreviation *
If timezone cannot be termined, no characters   CDT
%%      A % sign        %